<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Eigen: Lazy Evaluation and Aliasing</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],
    jax: ["input/TeX","output/HTML-CSS"],
});
</script>
<script type="text/javascript" async="async" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="eigendoxy.css" rel="stylesheet" type="text/css">
<!--  -->
<script type="text/javascript" src="eigen_navtree_hacks.js"></script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="Eigen_Silly_Professor_64x64.png"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname"><a href="http://eigen.tuxfamily.org">Eigen</a>
   &#160;<span id="projectnumber">3.4.90 (git rev 67eeba6e720c5745abc77ae6c92ce0a44aa7b7ae)</span>
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.svg"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('TopicLazyEvaluation.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">Lazy Evaluation and Aliasing </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Executive summary: Eigen has intelligent compile-time mechanisms to enable lazy evaluation and removing temporaries where appropriate. It will handle aliasing automatically in most cases, for example with matrix products. The automatic behavior can be overridden manually by using the <a class="el" href="classEigen_1_1DenseBase.html#aa73e57a2f0f7cfcb4ad4d55ea0b6414b">MatrixBase::eval()</a> and <a class="el" href="classEigen_1_1MatrixBase.html#a2c1085de7645f23f240876388457da0b">MatrixBase::noalias()</a> methods.</p>
<p>When you write a line of code involving a complex expression such as</p>
<div class="fragment"><div class="line">mat1 = mat2 + mat3 * (mat4 + mat5);</div>
</div><!-- fragment --><p>Eigen determines automatically, for each sub-expression, whether to evaluate it into a temporary variable. Indeed, in certain cases it is better to evaluate a sub-expression into a temporary variable, while in other cases it is better to avoid that.</p>
<p>A traditional math library without expression templates always evaluates all sub-expressions into temporaries. So with this code,</p>
<div class="fragment"><div class="line">vec1 = vec2 + vec3;</div>
</div><!-- fragment --><p>a traditional library would evaluate <code>vec2</code> + vec3 into a temporary <code>vec4</code> and then copy <code>vec4</code> into <code>vec1</code>. This is of course inefficient: the arrays are traversed twice, so there are a lot of useless load/store operations.</p>
<p>Expression-templates-based libraries can avoid evaluating sub-expressions into temporaries, which in many cases results in large speed improvements. This is called <em>lazy evaluation</em> as an expression is getting evaluated as late as possible. In Eigen <b>all expressions are lazy-evaluated</b>. More precisely, an expression starts to be evaluated once it is assigned to a matrix. Until then nothing happens beyond constructing the abstract expression tree. In contrast to most other expression-templates-based libraries, however, <b>Eigen might choose to evaluate some sub-expressions into temporaries</b>. There are two reasons for that: first, pure lazy evaluation is not always a good choice for performance; second, pure lazy evaluation can be very dangerous, for example with matrix products: doing <code>mat = mat*mat</code> gives a wrong result if the matrix product is directly evaluated within the destination matrix, because of the way matrix product works.</p>
<p>For these reasons, Eigen has intelligent compile-time mechanisms to determine automatically which sub-expression should be evaluated into a temporary variable.</p>
<p>So in the basic example,</p>
<div class="fragment"><div class="line">mat1 = mat2 + mat3;</div>
</div><!-- fragment --><p>Eigen chooses not to introduce any temporary. Thus the arrays are traversed only once, producing optimized code. If you really want to force immediate evaluation, use <a class="el" href="classEigen_1_1DenseBase.html#aa73e57a2f0f7cfcb4ad4d55ea0b6414b">eval()</a>:</p>
<div class="fragment"><div class="line">mat1 = (mat2 + mat3).eval();</div>
</div><!-- fragment --><p>Here is now a more involved example:</p>
<div class="fragment"><div class="line">mat1 = -mat2 + mat3 + 5 * mat4;</div>
</div><!-- fragment --><p>Here again Eigen won't introduce any temporary, thus producing a single <b>fused</b> evaluation loop, which is clearly the correct choice.</p>
<h1><a class="anchor" id="TopicLazyEvaluationWhichExpr"></a>
Which sub-expressions are evaluated into temporaries?</h1>
<p>The default evaluation strategy is to fuse the operations in a single loop, and Eigen will choose it except in a few circumstances.</p>
<p><b>The first circumstance</b> in which Eigen chooses to evaluate a sub-expression is when it sees an assignment <code>a = b;</code> and the expression <code>b</code> has the evaluate-before-assigning <a class="el" href="group__flags.html">flag</a>. The most important example of such an expression is the <a class="el" href="classEigen_1_1Product.html">matrix product expression</a>. For example, when you do</p>
<div class="fragment"><div class="line">mat = mat * mat;</div>
</div><!-- fragment --><p>Eigen will evaluate <code>mat * mat</code> into a temporary matrix, and then copies it into the original <code>mat</code>. This guarantees a correct result as we saw above that lazy evaluation gives wrong results with matrix products. It also doesn't cost much, as the cost of the matrix product itself is much higher. Note that this temporary is introduced at evaluation time only, that is, within operator= in this example. The expression <code>mat * mat</code> still return a abstract product type.</p>
<p>What if you know that the result does no alias the operand of the product and want to force lazy evaluation? Then use <a class="el" href="classEigen_1_1MatrixBase.html#a2c1085de7645f23f240876388457da0b">.noalias()</a> instead. Here is an example:</p>
<div class="fragment"><div class="line">mat1.noalias() = mat2 * mat2;</div>
</div><!-- fragment --><p>Here, since we know that mat2 is not the same matrix as mat1, we know that lazy evaluation is not dangerous, so we may force lazy evaluation. Concretely, the effect of noalias() here is to bypass the evaluate-before-assigning <a class="el" href="group__flags.html">flag</a>.</p>
<p><b>The second circumstance</b> in which Eigen chooses to evaluate a sub-expression, is when it sees a nested expression such as <code>a + b</code> where <code>b</code> is already an expression having the evaluate-before-nesting <a class="el" href="group__flags.html">flag</a>. Again, the most important example of such an expression is the <a class="el" href="classEigen_1_1Product.html">matrix product expression</a>. For example, when you do</p>
<div class="fragment"><div class="line">mat1 = mat2 * mat3 + mat4 * mat5;</div>
</div><!-- fragment --><p>the products <code>mat2 * mat3</code> and <code>mat4 * mat5</code> gets evaluated separately into temporary matrices before being summed up in <code>mat1</code>. Indeed, to be efficient matrix products need to be evaluated within a destination matrix at hand, and not as simple "dot products". For small matrices, however, you might want to enforce a "dot-product" based lazy evaluation with lazyProduct(). Again, it is important to understand that those temporaries are created at evaluation time only, that is in operator =. See TopicPitfalls_auto_keyword for common pitfalls regarding this remark.</p>
<p><b>The third circumstance</b> in which Eigen chooses to evaluate a sub-expression, is when its cost model shows that the total cost of an operation is reduced if a sub-expression gets evaluated into a temporary. Indeed, in certain cases, an intermediate result is sufficiently costly to compute and is reused sufficiently many times, that is worth "caching". Here is an example:</p>
<div class="fragment"><div class="line">mat1 = mat2 * (mat3 + mat4);</div>
</div><!-- fragment --><p>Here, provided the matrices have at least 2 rows and 2 columns, each coefficient of the expression <code>mat3 + mat4</code> is going to be used several times in the matrix product. Instead of computing the sum every time, it is much better to compute it once and store it in a temporary variable. Eigen understands this and evaluates <code>mat3 + mat4</code> into a temporary variable before evaluating the product. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Thu Apr 21 2022 13:07:55 for Eigen by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li>
  </ul>
</div>
</body>
</html>
